/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.jdbc.core;

import java.util.Collection;
import java.util.List;
import java.util.Map;

import org.springframework.dao.DataAccessException;
import org.springframework.dao.IncorrectResultSizeDataAccessException;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.jdbc.support.rowset.SqlRowSet;
import org.springframework.lang.Nullable;

/**
 * Interface specifying a basic set of JDBC operations.
 * Implemented by {@link JdbcTemplate}. Not often used directly, but a useful
 * option to enhance testability, as it can easily be mocked or stubbed.
 *
 * <p>Alternatively, the standard JDBC infrastructure can be mocked.
 * However, mocking this interface constitutes significantly less work.
 * As an alternative to a mock objects approach to testing data access code,
 * consider the powerful integration testing support provided in the
 * {@code org.springframework.test} package, shipped in
 * {@code spring-test.jar}.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @see JdbcTemplate
 */
public interface JdbcOperations {

    //-------------------------------------------------------------------------
    // Methods dealing with a plain java.sql.Connection
    //-------------------------------------------------------------------------

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC Connection. This allows for implementing arbitrary
     * data access operations, within Spring's managed JDBC environment:
     * that is, participating in Spring-managed transactions and converting
     * JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param action the callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(ConnectionCallback<T> action) throws DataAccessException;


    //-------------------------------------------------------------------------
    // Methods dealing with static SQL (java.sql.Statement)
    //-------------------------------------------------------------------------

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC Statement. This allows for implementing arbitrary data
     * access operations on a single Statement, within Spring's managed JDBC
     * environment: that is, participating in Spring-managed transactions and
     * converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param action callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(StatementCallback<T> action) throws DataAccessException;

    /**
     * Issue a single SQL execute, typically a DDL statement.
     *
     * @param sql static SQL to execute
     * @throws DataAccessException if there is any problem
     */
    void execute(String sql) throws DataAccessException;

    /**
     * Execute a query given static SQL, reading the ResultSet with a
     * ResultSetExtractor.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code query} method with {@code null} as argument array.
     *
     * @param sql the SQL query to execute
     * @param rse object that will extract all rows of results
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if there is any problem executing the query
     * @see #query(String, Object[], ResultSetExtractor)
     */
    @Nullable
    <T> T query(String sql, ResultSetExtractor<T> rse) throws DataAccessException;

    /**
     * Execute a query given static SQL, reading the ResultSet on a per-row
     * basis with a RowCallbackHandler.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code query} method with {@code null} as argument array.
     *
     * @param sql the SQL query to execute
     * @param rch object that will extract results, one row at a time
     * @throws DataAccessException if there is any problem executing the query
     * @see #query(String, Object[], RowCallbackHandler)
     */
    void query(String sql, RowCallbackHandler rch) throws DataAccessException;

    /**
     * Execute a query given static SQL, mapping each row to a Java object
     * via a RowMapper.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code query} method with {@code null} as argument array.
     *
     * @param sql       the SQL query to execute
     * @param rowMapper object that will map one object per row
     * @return the result List, containing mapped objects
     * @throws DataAccessException if there is any problem executing the query
     * @see #query(String, Object[], RowMapper)
     */
    <T> List<T> query(String sql, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Execute a query given static SQL, mapping a single result row to a Java
     * object via a RowMapper.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@link #queryForObject(String, RowMapper, Object...)} method with
     * {@code null} as argument array.
     *
     * @param sql       the SQL query to execute
     * @param rowMapper object that will map one object per row
     * @return the single mapped object (may be {@code null} if the given
     * {@link RowMapper} returned {@code} null)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if there is any problem executing the query
     * @see #queryForObject(String, Object[], RowMapper)
     */
    @Nullable
    <T> T queryForObject(String sql, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Execute a query for a result object, given static SQL.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@link #queryForObject(String, Class, Object...)} method with
     * {@code null} as argument array.
     * <p>This method is useful for running static SQL with a known outcome.
     * The query is expected to be a single row/single column query; the returned
     * result will be directly mapped to the corresponding object type.
     *
     * @param sql          the SQL query to execute
     * @param requiredType the type that the result object is expected to match
     * @return the result object of the required type, or {@code null} in case of SQL NULL
     * @throws IncorrectResultSizeDataAccessException if the query does not return
     *                                                exactly one row, or does not return exactly one column in that row
     * @throws DataAccessException                    if there is any problem executing the query
     * @see #queryForObject(String, Object[], Class)
     */
    @Nullable
    <T> T queryForObject(String sql, Class<T> requiredType) throws DataAccessException;

    /**
     * Execute a query for a result Map, given static SQL.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@link #queryForMap(String, Object...)} method with {@code null}
     * as argument array.
     * <p>The query is expected to be a single row query; the result row will be
     * mapped to a Map (one entry for each column, using the column name as the key).
     *
     * @param sql the SQL query to execute
     * @return the result Map (one entry for each column, using the
     * column name as the key)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if there is any problem executing the query
     * @see #queryForMap(String, Object[])
     * @see ColumnMapRowMapper
     */
    Map<String, Object> queryForMap(String sql) throws DataAccessException;

    /**
     * Execute a query for a result list, given static SQL.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code queryForList} method with {@code null} as argument array.
     * <p>The results will be mapped to a List (one entry for each row) of
     * result objects, each of them matching the specified element type.
     *
     * @param sql         the SQL query to execute
     * @param elementType the required type of element in the result list
     *                    (for example, {@code Integer.class})
     * @return a List of objects that match the specified element type
     * @throws DataAccessException if there is any problem executing the query
     * @see #queryForList(String, Object[], Class)
     * @see SingleColumnRowMapper
     */
    <T> List<T> queryForList(String sql, Class<T> elementType) throws DataAccessException;

    /**
     * Execute a query for a result list, given static SQL.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code queryForList} method with {@code null} as argument array.
     * <p>The results will be mapped to a List (one entry for each row) of
     * Maps (one entry for each column using the column name as the key).
     * Each element in the list will be of the form returned by this interface's
     * queryForMap() methods.
     *
     * @param sql the SQL query to execute
     * @return an List that contains a Map per row
     * @throws DataAccessException if there is any problem executing the query
     * @see #queryForList(String, Object[])
     */
    List<Map<String, Object>> queryForList(String sql) throws DataAccessException;

    /**
     * Execute a query for a SqlRowSet, given static SQL.
     * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
     * execute a static query with a PreparedStatement, use the overloaded
     * {@code queryForRowSet} method with {@code null} as argument array.
     * <p>The results will be mapped to an SqlRowSet which holds the data in a
     * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
     * <p>Note that, for the default implementation, JDBC RowSet support needs to
     * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
     * class is used, which is part of JDK 1.5+ and also available separately as part of
     * Sun's JDBC RowSet Implementations download (rowset.jar).
     *
     * @param sql the SQL query to execute
     * @return a SqlRowSet representation (possibly a wrapper around a
     * {@code javax.sql.rowset.CachedRowSet})
     * @throws DataAccessException if there is any problem executing the query
     * @see #queryForRowSet(String, Object[])
     * @see SqlRowSetResultSetExtractor
     * @see javax.sql.rowset.CachedRowSet
     */
    SqlRowSet queryForRowSet(String sql) throws DataAccessException;

    /**
     * Issue a single SQL update operation (such as an insert, update or delete statement).
     *
     * @param sql static SQL to execute
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem.
     */
    int update(String sql) throws DataAccessException;

    /**
     * Issue multiple SQL updates on a single JDBC Statement using batching.
     * <p>Will fall back to separate updates on a single Statement if the JDBC
     * driver does not support batch updates.
     *
     * @param sql defining an array of SQL statements that will be executed.
     * @return an array of the number of rows affected by each statement
     * @throws DataAccessException if there is any problem executing the batch
     */
    int[] batchUpdate(String... sql) throws DataAccessException;


    //-------------------------------------------------------------------------
    // Methods dealing with prepared statements
    //-------------------------------------------------------------------------

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC PreparedStatement. This allows for implementing arbitrary
     * data access operations on a single Statement, within Spring's managed
     * JDBC environment: that is, participating in Spring-managed transactions
     * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param psc    object that can create a PreparedStatement given a Connection
     * @param action callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(PreparedStatementCreator psc, PreparedStatementCallback<T> action) throws DataAccessException;

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC PreparedStatement. This allows for implementing arbitrary
     * data access operations on a single Statement, within Spring's managed
     * JDBC environment: that is, participating in Spring-managed transactions
     * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param sql    the SQL to execute
     * @param action callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(String sql, PreparedStatementCallback<T> action) throws DataAccessException;

    /**
     * Query using a prepared statement, reading the ResultSet with a
     * ResultSetExtractor.
     * <p>A PreparedStatementCreator can either be implemented directly or
     * configured through a PreparedStatementCreatorFactory.
     *
     * @param psc object that can create a PreparedStatement given a Connection
     * @param rse object that will extract results
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if there is any problem
     * @see PreparedStatementCreatorFactory
     */
    @Nullable
    <T> T query(PreparedStatementCreator psc, ResultSetExtractor<T> rse) throws DataAccessException;

    /**
     * Query using a prepared statement, reading the ResultSet with a
     * ResultSetExtractor.
     *
     * @param sql the SQL query to execute
     * @param pss object that knows how to set values on the prepared statement.
     *            If this is {@code null}, the SQL will be assumed to contain no bind parameters.
     *            Even if there are no bind parameters, this object may be used to
     *            set fetch size and other performance options.
     * @param rse object that will extract results
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T query(String sql, @Nullable PreparedStatementSetter pss, ResultSetExtractor<T> rse) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, reading the ResultSet with a
     * ResultSetExtractor.
     *
     * @param sql      the SQL query to execute
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @param rse      object that will extract results
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if the query fails
     * @see java.sql.Types
     */
    @Nullable
    <T> T query(String sql, Object[] args, int[] argTypes, ResultSetExtractor<T> rse) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, reading the ResultSet with a
     * ResultSetExtractor.
     *
     * @param sql  the SQL query to execute
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @param rse  object that will extract results
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if the query fails
     */
    @Nullable
    <T> T query(String sql, Object[] args, ResultSetExtractor<T> rse) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, reading the ResultSet with a
     * ResultSetExtractor.
     *
     * @param sql  the SQL query to execute
     * @param rse  object that will extract results
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @return an arbitrary result object, as returned by the ResultSetExtractor
     * @throws DataAccessException if the query fails
     * @since 3.0.1
     */
    @Nullable
    <T> T query(String sql, ResultSetExtractor<T> rse, @Nullable Object... args) throws DataAccessException;

    /**
     * Query using a prepared statement, reading the ResultSet on a per-row
     * basis with a RowCallbackHandler.
     * <p>A PreparedStatementCreator can either be implemented directly or
     * configured through a PreparedStatementCreatorFactory.
     *
     * @param psc object that can create a PreparedStatement given a Connection
     * @param rch object that will extract results, one row at a time
     * @throws DataAccessException if there is any problem
     * @see PreparedStatementCreatorFactory
     */
    void query(PreparedStatementCreator psc, RowCallbackHandler rch) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * PreparedStatementSetter implementation that knows how to bind values
     * to the query, reading the ResultSet on a per-row basis with a
     * RowCallbackHandler.
     *
     * @param sql the SQL query to execute
     * @param pss object that knows how to set values on the prepared statement.
     *            If this is {@code null}, the SQL will be assumed to contain no bind parameters.
     *            Even if there are no bind parameters, this object may be used to
     *            set fetch size and other performance options.
     * @param rch object that will extract results, one row at a time
     * @throws DataAccessException if the query fails
     */
    void query(String sql, @Nullable PreparedStatementSetter pss, RowCallbackHandler rch) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list of
     * arguments to bind to the query, reading the ResultSet on a per-row basis
     * with a RowCallbackHandler.
     *
     * @param sql      the SQL query to execute
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @param rch      object that will extract results, one row at a time
     * @throws DataAccessException if the query fails
     * @see java.sql.Types
     */
    void query(String sql, Object[] args, int[] argTypes, RowCallbackHandler rch) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list of
     * arguments to bind to the query, reading the ResultSet on a per-row basis
     * with a RowCallbackHandler.
     *
     * @param sql  the SQL query to execute
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @param rch  object that will extract results, one row at a time
     * @throws DataAccessException if the query fails
     */
    void query(String sql, Object[] args, RowCallbackHandler rch) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list of
     * arguments to bind to the query, reading the ResultSet on a per-row basis
     * with a RowCallbackHandler.
     *
     * @param sql  the SQL query to execute
     * @param rch  object that will extract results, one row at a time
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @throws DataAccessException if the query fails
     * @since 3.0.1
     */
    void query(String sql, RowCallbackHandler rch, @Nullable Object... args) throws DataAccessException;

    /**
     * Query using a prepared statement, mapping each row to a Java object
     * via a RowMapper.
     * <p>A PreparedStatementCreator can either be implemented directly or
     * configured through a PreparedStatementCreatorFactory.
     *
     * @param psc       object that can create a PreparedStatement given a Connection
     * @param rowMapper object that will map one object per row
     * @return the result List, containing mapped objects
     * @throws DataAccessException if there is any problem
     * @see PreparedStatementCreatorFactory
     */
    <T> List<T> query(PreparedStatementCreator psc, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * PreparedStatementSetter implementation that knows how to bind values
     * to the query, mapping each row to a Java object via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param pss       object that knows how to set values on the prepared statement.
     *                  If this is {@code null}, the SQL will be assumed to contain no bind parameters.
     *                  Even if there are no bind parameters, this object may be used to
     *                  set fetch size and other performance options.
     * @param rowMapper object that will map one object per row
     * @return the result List, containing mapped objects
     * @throws DataAccessException if the query fails
     */
    <T> List<T> query(String sql, @Nullable PreparedStatementSetter pss, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping each row to a Java object
     * via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param args      arguments to bind to the query
     * @param argTypes  the SQL types of the arguments
     *                  (constants from {@code java.sql.Types})
     * @param rowMapper object that will map one object per row
     * @return the result List, containing mapped objects
     * @throws DataAccessException if the query fails
     * @see java.sql.Types
     */
    <T> List<T> query(String sql, Object[] args, int[] argTypes, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping each row to a Java object
     * via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param args      arguments to bind to the query
     *                  (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                  may also contain {@link SqlParameterValue} objects which indicate not
     *                  only the argument value but also the SQL type and optionally the scale
     * @param rowMapper object that will map one object per row
     * @return the result List, containing mapped objects
     * @throws DataAccessException if the query fails
     */
    <T> List<T> query(String sql, Object[] args, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping each row to a Java object
     * via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param rowMapper object that will map one object per row
     * @param args      arguments to bind to the query
     *                  (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                  may also contain {@link SqlParameterValue} objects which indicate not
     *                  only the argument value but also the SQL type and optionally the scale
     * @return the result List, containing mapped objects
     * @throws DataAccessException if the query fails
     * @since 3.0.1
     */
    <T> List<T> query(String sql, RowMapper<T> rowMapper, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping a single result row to a
     * Java object via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param args      arguments to bind to the query
     *                  (leaving it to the PreparedStatement to guess the corresponding SQL type)
     * @param argTypes  the SQL types of the arguments
     *                  (constants from {@code java.sql.Types})
     * @param rowMapper object that will map one object per row
     * @return the single mapped object (may be {@code null} if the given
     * {@link RowMapper} returned {@code} null)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if the query fails
     */
    @Nullable
    <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> rowMapper)
            throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping a single result row to a
     * Java object via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param args      arguments to bind to the query
     *                  (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                  may also contain {@link SqlParameterValue} objects which indicate not
     *                  only the argument value but also the SQL type and optionally the scale
     * @param rowMapper object that will map one object per row
     * @return the single mapped object (may be {@code null} if the given
     * {@link RowMapper} returned {@code} null)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if the query fails
     */
    @Nullable
    <T> T queryForObject(String sql, Object[] args, RowMapper<T> rowMapper) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a list
     * of arguments to bind to the query, mapping a single result row to a
     * Java object via a RowMapper.
     *
     * @param sql       the SQL query to execute
     * @param rowMapper object that will map one object per row
     * @param args      arguments to bind to the query
     *                  (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                  may also contain {@link SqlParameterValue} objects which indicate not
     *                  only the argument value but also the SQL type and optionally the scale
     * @return the single mapped object (may be {@code null} if the given
     * {@link RowMapper} returned {@code} null)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if the query fails
     * @since 3.0.1
     */
    @Nullable
    <T> T queryForObject(String sql, RowMapper<T> rowMapper, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result object.
     * <p>The query is expected to be a single row/single column query; the returned
     * result will be directly mapped to the corresponding object type.
     *
     * @param sql          the SQL query to execute
     * @param args         arguments to bind to the query
     * @param argTypes     the SQL types of the arguments
     *                     (constants from {@code java.sql.Types})
     * @param requiredType the type that the result object is expected to match
     * @return the result object of the required type, or {@code null} in case of SQL NULL
     * @throws IncorrectResultSizeDataAccessException if the query does not return
     *                                                exactly one row, or does not return exactly one column in that row
     * @throws DataAccessException                    if the query fails
     * @see #queryForObject(String, Class)
     * @see java.sql.Types
     */
    @Nullable
    <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> requiredType)
            throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result object.
     * <p>The query is expected to be a single row/single column query; the returned
     * result will be directly mapped to the corresponding object type.
     *
     * @param sql          the SQL query to execute
     * @param args         arguments to bind to the query
     *                     (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                     may also contain {@link SqlParameterValue} objects which indicate not
     *                     only the argument value but also the SQL type and optionally the scale
     * @param requiredType the type that the result object is expected to match
     * @return the result object of the required type, or {@code null} in case of SQL NULL
     * @throws IncorrectResultSizeDataAccessException if the query does not return
     *                                                exactly one row, or does not return exactly one column in that row
     * @throws DataAccessException                    if the query fails
     * @see #queryForObject(String, Class)
     */
    @Nullable
    <T> T queryForObject(String sql, Object[] args, Class<T> requiredType) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result object.
     * <p>The query is expected to be a single row/single column query; the returned
     * result will be directly mapped to the corresponding object type.
     *
     * @param sql          the SQL query to execute
     * @param requiredType the type that the result object is expected to match
     * @param args         arguments to bind to the query
     *                     (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                     may also contain {@link SqlParameterValue} objects which indicate not
     *                     only the argument value but also the SQL type and optionally the scale
     * @return the result object of the required type, or {@code null} in case of SQL NULL
     * @throws IncorrectResultSizeDataAccessException if the query does not return
     *                                                exactly one row, or does not return exactly one column in that row
     * @throws DataAccessException                    if the query fails
     * @see #queryForObject(String, Class)
     * @since 3.0.1
     */
    @Nullable
    <T> T queryForObject(String sql, Class<T> requiredType, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result Map.
     * <p>The query is expected to be a single row query; the result row will be
     * mapped to a Map (one entry for each column, using the column name as the key).
     *
     * @param sql      the SQL query to execute
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @return the result Map (one entry for each column, using the
     * column name as the key)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if the query fails
     * @see #queryForMap(String)
     * @see ColumnMapRowMapper
     * @see java.sql.Types
     */
    Map<String, Object> queryForMap(String sql, Object[] args, int[] argTypes) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result Map.
     * The queryForMap() methods defined by this interface are appropriate
     * when you don't have a domain model. Otherwise, consider using
     * one of the queryForObject() methods.
     * <p>The query is expected to be a single row query; the result row will be
     * mapped to a Map (one entry for each column, using the column name as the key).
     *
     * @param sql  the SQL query to execute
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @return the result Map (one entry for each column, using the
     * column name as the key)
     * @throws IncorrectResultSizeDataAccessException if the query does not
     *                                                return exactly one row
     * @throws DataAccessException                    if the query fails
     * @see #queryForMap(String)
     * @see ColumnMapRowMapper
     */
    Map<String, Object> queryForMap(String sql, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result list.
     * <p>The results will be mapped to a List (one entry for each row) of
     * result objects, each of them matching the specified element type.
     *
     * @param sql         the SQL query to execute
     * @param args        arguments to bind to the query
     * @param argTypes    the SQL types of the arguments
     *                    (constants from {@code java.sql.Types})
     * @param elementType the required type of element in the result list
     *                    (for example, {@code Integer.class})
     * @return a List of objects that match the specified element type
     * @throws DataAccessException if the query fails
     * @see #queryForList(String, Class)
     * @see SingleColumnRowMapper
     */
    <T> List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> elementType)
            throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result list.
     * <p>The results will be mapped to a List (one entry for each row) of
     * result objects, each of them matching the specified element type.
     *
     * @param sql         the SQL query to execute
     * @param args        arguments to bind to the query
     *                    (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                    may also contain {@link SqlParameterValue} objects which indicate not
     *                    only the argument value but also the SQL type and optionally the scale
     * @param elementType the required type of element in the result list
     *                    (for example, {@code Integer.class})
     * @return a List of objects that match the specified element type
     * @throws DataAccessException if the query fails
     * @see #queryForList(String, Class)
     * @see SingleColumnRowMapper
     */
    <T> List<T> queryForList(String sql, Object[] args, Class<T> elementType) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result list.
     * <p>The results will be mapped to a List (one entry for each row) of
     * result objects, each of them matching the specified element type.
     *
     * @param sql         the SQL query to execute
     * @param elementType the required type of element in the result list
     *                    (for example, {@code Integer.class})
     * @param args        arguments to bind to the query
     *                    (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *                    may also contain {@link SqlParameterValue} objects which indicate not
     *                    only the argument value but also the SQL type and optionally the scale
     * @return a List of objects that match the specified element type
     * @throws DataAccessException if the query fails
     * @see #queryForList(String, Class)
     * @see SingleColumnRowMapper
     * @since 3.0.1
     */
    <T> List<T> queryForList(String sql, Class<T> elementType, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result list.
     * <p>The results will be mapped to a List (one entry for each row) of
     * Maps (one entry for each column, using the column name as the key).
     * Thus  Each element in the list will be of the form returned by this interface's
     * queryForMap() methods.
     *
     * @param sql      the SQL query to execute
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @return a List that contains a Map per row
     * @throws DataAccessException if the query fails
     * @see #queryForList(String)
     * @see java.sql.Types
     */
    List<Map<String, Object>> queryForList(String sql, Object[] args, int[] argTypes) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a result list.
     * <p>The results will be mapped to a List (one entry for each row) of
     * Maps (one entry for each column, using the column name as the key).
     * Each element in the list will be of the form returned by this interface's
     * queryForMap() methods.
     *
     * @param sql  the SQL query to execute
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @return a List that contains a Map per row
     * @throws DataAccessException if the query fails
     * @see #queryForList(String)
     */
    List<Map<String, Object>> queryForList(String sql, @Nullable Object... args) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a SqlRowSet.
     * <p>The results will be mapped to an SqlRowSet which holds the data in a
     * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
     * <p>Note that, for the default implementation, JDBC RowSet support needs to
     * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
     * class is used, which is part of JDK 1.5+ and also available separately as part of
     * Sun's JDBC RowSet Implementations download (rowset.jar).
     *
     * @param sql      the SQL query to execute
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @return a SqlRowSet representation (possibly a wrapper around a
     * {@code javax.sql.rowset.CachedRowSet})
     * @throws DataAccessException if there is any problem executing the query
     * @see #queryForRowSet(String)
     * @see SqlRowSetResultSetExtractor
     * @see javax.sql.rowset.CachedRowSet
     * @see java.sql.Types
     */
    SqlRowSet queryForRowSet(String sql, Object[] args, int[] argTypes) throws DataAccessException;

    /**
     * Query given SQL to create a prepared statement from SQL and a
     * list of arguments to bind to the query, expecting a SqlRowSet.
     * <p>The results will be mapped to an SqlRowSet which holds the data in a
     * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
     * <p>Note that, for the default implementation, JDBC RowSet support needs to
     * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
     * class is used, which is part of JDK 1.5+ and also available separately as part of
     * Sun's JDBC RowSet Implementations download (rowset.jar).
     *
     * @param sql  the SQL query to execute
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @return a SqlRowSet representation (possibly a wrapper around a
     * {@code javax.sql.rowset.CachedRowSet})
     * @throws DataAccessException if there is any problem executing the query
     * @see #queryForRowSet(String)
     * @see SqlRowSetResultSetExtractor
     * @see javax.sql.rowset.CachedRowSet
     */
    SqlRowSet queryForRowSet(String sql, @Nullable Object... args) throws DataAccessException;

    /**
     * Issue a single SQL update operation (such as an insert, update or delete statement)
     * using a PreparedStatementCreator to provide SQL and any required parameters.
     * <p>A PreparedStatementCreator can either be implemented directly or
     * configured through a PreparedStatementCreatorFactory.
     *
     * @param psc object that provides SQL and any necessary parameters
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem issuing the update
     * @see PreparedStatementCreatorFactory
     */
    int update(PreparedStatementCreator psc) throws DataAccessException;

    /**
     * Issue an update statement using a PreparedStatementCreator to provide SQL and
     * any required parameters. Generated keys will be put into the given KeyHolder.
     * <p>Note that the given PreparedStatementCreator has to create a statement
     * with activated extraction of generated keys (a JDBC 3.0 feature). This can
     * either be done directly or through using a PreparedStatementCreatorFactory.
     *
     * @param psc                object that provides SQL and any necessary parameters
     * @param generatedKeyHolder a KeyHolder that will hold the generated keys
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem issuing the update
     * @see PreparedStatementCreatorFactory
     * @see org.springframework.jdbc.support.GeneratedKeyHolder
     */
    int update(PreparedStatementCreator psc, KeyHolder generatedKeyHolder) throws DataAccessException;

    /**
     * Issue an update statement using a PreparedStatementSetter to set bind parameters,
     * with given SQL. Simpler than using a PreparedStatementCreator as this method
     * will create the PreparedStatement: The PreparedStatementSetter just needs to
     * set parameters.
     *
     * @param sql the SQL containing bind parameters
     * @param pss helper that sets bind parameters. If this is {@code null}
     *            we run an update with static SQL.
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem issuing the update
     */
    int update(String sql, @Nullable PreparedStatementSetter pss) throws DataAccessException;

    /**
     * Issue a single SQL update operation (such as an insert, update or delete statement)
     * via a prepared statement, binding the given arguments.
     *
     * @param sql      the SQL containing bind parameters
     * @param args     arguments to bind to the query
     * @param argTypes the SQL types of the arguments
     *                 (constants from {@code java.sql.Types})
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem issuing the update
     * @see java.sql.Types
     */
    int update(String sql, Object[] args, int[] argTypes) throws DataAccessException;

    /**
     * Issue a single SQL update operation (such as an insert, update or delete statement)
     * via a prepared statement, binding the given arguments.
     *
     * @param sql  the SQL containing bind parameters
     * @param args arguments to bind to the query
     *             (leaving it to the PreparedStatement to guess the corresponding SQL type);
     *             may also contain {@link SqlParameterValue} objects which indicate not
     *             only the argument value but also the SQL type and optionally the scale
     * @return the number of rows affected
     * @throws DataAccessException if there is any problem issuing the update
     */
    int update(String sql, @Nullable Object... args) throws DataAccessException;

    /**
     * Issue multiple update statements on a single PreparedStatement,
     * using batch updates and a BatchPreparedStatementSetter to set values.
     * <p>Will fall back to separate updates on a single PreparedStatement
     * if the JDBC driver does not support batch updates.
     *
     * @param sql defining PreparedStatement that will be reused.
     *            All statements in the batch will use the same SQL.
     * @param pss object to set parameters on the PreparedStatement
     *            created by this method
     * @return an array of the number of rows affected by each statement
     * @throws DataAccessException if there is any problem issuing the update
     */
    int[] batchUpdate(String sql, BatchPreparedStatementSetter pss) throws DataAccessException;

    /**
     * Execute a batch using the supplied SQL statement with the batch of supplied arguments.
     *
     * @param sql       the SQL statement to execute
     * @param batchArgs the List of Object arrays containing the batch of arguments for the query
     * @return an array containing the numbers of rows affected by each update in the batch
     */
    int[] batchUpdate(String sql, List<Object[]> batchArgs) throws DataAccessException;

    /**
     * Execute a batch using the supplied SQL statement with the batch of supplied arguments.
     *
     * @param sql       the SQL statement to execute.
     * @param batchArgs the List of Object arrays containing the batch of arguments for the query
     * @param argTypes  the SQL types of the arguments
     *                  (constants from {@code java.sql.Types})
     * @return an array containing the numbers of rows affected by each update in the batch
     */
    int[] batchUpdate(String sql, List<Object[]> batchArgs, int[] argTypes) throws DataAccessException;

    /**
     * Execute multiple batches using the supplied SQL statement with the collect of supplied arguments.
     * The arguments' values will be set using the ParameterizedPreparedStatementSetter.
     * Each batch should be of size indicated in 'batchSize'.
     *
     * @param sql       the SQL statement to execute.
     * @param batchArgs the List of Object arrays containing the batch of arguments for the query
     * @param batchSize batch size
     * @param pss       the ParameterizedPreparedStatementSetter to use
     * @return an array containing for each batch another array containing the numbers of rows affected
     * by each update in the batch
     */
    <T> int[][] batchUpdate(String sql, Collection<T> batchArgs, int batchSize,
                            ParameterizedPreparedStatementSetter<T> pss) throws DataAccessException;


    //-------------------------------------------------------------------------
    // Methods dealing with callable statements
    //-------------------------------------------------------------------------

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC CallableStatement. This allows for implementing arbitrary
     * data access operations on a single Statement, within Spring's managed
     * JDBC environment: that is, participating in Spring-managed transactions
     * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param csc    object that can create a CallableStatement given a Connection
     * @param action callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(CallableStatementCreator csc, CallableStatementCallback<T> action) throws DataAccessException;

    /**
     * Execute a JDBC data access operation, implemented as callback action
     * working on a JDBC CallableStatement. This allows for implementing arbitrary
     * data access operations on a single Statement, within Spring's managed
     * JDBC environment: that is, participating in Spring-managed transactions
     * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
     * <p>The callback action can return a result object, for example a
     * domain object or a collection of domain objects.
     *
     * @param callString the SQL call string to execute
     * @param action     callback object that specifies the action
     * @return a result object returned by the action, or {@code null}
     * @throws DataAccessException if there is any problem
     */
    @Nullable
    <T> T execute(String callString, CallableStatementCallback<T> action) throws DataAccessException;

    /**
     * Execute a SQL call using a CallableStatementCreator to provide SQL and any
     * required parameters.
     *
     * @param csc                object that provides SQL and any necessary parameters
     * @param declaredParameters list of declared SqlParameter objects
     * @return a Map of extracted out parameters
     * @throws DataAccessException if there is any problem issuing the update
     */
    Map<String, Object> call(CallableStatementCreator csc, List<SqlParameter> declaredParameters)
            throws DataAccessException;

}
